---
title: Library Examples
description: Practical examples of how to use the Zoi library in your Rust code.
---

This page provides practical, copy-paste-ready examples for using Zoi's library features.

## Basic Package Installation

This example demonstrates the most common use case: installing a package using the default settings. We will install the `hello` package, automatically confirming any prompts.

### Code

```rust
use zoi::{install, InstallMode, types::InstallReason};

fn main() {
    let package_source = "hello";

    println!("Attempting to install '{}'...", package_source);

    // Call the install function with default preferences.
    let result = zoi::install(
        package_source,
        InstallMode::PreferBinary, // Try to get a binary, fall back to source.
        false,                     // Don't force re-installation.
        InstallReason::Direct,     // This is a direct request from the user.
        true,                      // `non_interactive`: Automatically say "yes" to any prompts.
    );

    // Check the result and print a message.
    match result {
        Ok(()) => println!("'{}' was installed successfully!", package_source),
        Err(e) => eprintln!("Error installing '{}': {}", package_source, e),
    }
}
```

## Listing Installed Packages

You can easily get a list of all packages currently installed by Zoi.

### Code

```rust
use zoi::get_installed_packages;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Fetching installed packages...");
    let installed_packages = get_installed_packages()?;

    if installed_packages.is_empty() {
        println!("No packages are installed.");
    } else {
        println!("Installed packages:");
        for pkg in installed_packages {
            println!(
                "- {} (Version: {}, Repo: {}, Scope: {:?})",
                pkg.name,
                pkg.version,
                pkg.repo,
                pkg.scope
            );
        }
    }
    Ok(())
}
```

## Resolving Package Information

Before installing, you might want to inspect a package's metadata.

### Code

```rust
use zoi::resolve_package;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let package_source = "git";
    println!("Resolving package info for '{}'...", package_source);

    match resolve_package(package_source) {
        Ok(pkg) => {
            println!("Successfully resolved package: {}", pkg.name);
            println!("  Description: {}", pkg.description);
            println!("  License: {}", pkg.license);
            println!("  Maintainer: {} <{}>", pkg.maintainer.name, pkg.maintainer.email);
        }
        Err(e) => eprintln!("Error resolving package: {}", e),
    }

    Ok(())
}
```

## Updating a Package

This example shows how to check for and apply updates to an installed package.

### Code

```rust
use zoi::{update, UpdateResult};

fn main() {
    let package_source = "hello";

    println!("Checking for updates for '{}'...", package_source);

    // Call the update function.
    match zoi::update(package_source, true) {
        Ok(result) => match result {
            UpdateResult::Updated { from, to } => {
                println!("Successfully updated '{}' from v{} to v{}", package_source, from, to);
            }
            UpdateResult::AlreadyUpToDate => {
                println!("'{}' is already up to date.", package_source);
            }
            UpdateResult::Pinned => {
                println!("'{}' is pinned and was not updated.", package_source);
            }
        },
        Err(e) => {
            // This can happen if the package is not installed,
            // or if the user cancels the update prompt.
            eprintln!("Error updating '{}': {}", package_source, e);
        }
    }
}
```

## Pinning a Package

Pinning a package prevents it from being accidentally updated.

### Code

```rust
use zoi::{pin, unpin, get_pinned_packages};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let package_to_pin = "hello";
    let version_to_pin = "1.0.0";

    println!("Pinning {} to version {}", package_to_pin, version_to_pin);
    pin(package_to_pin, version_to_pin)?;

    println!("\nCurrently pinned packages:");
    let pinned = get_pinned_packages()?;
    for p in &pinned {
        println!("- {}@{}", p.name, p.version);
    }

    println!("\nUnpinning {}...", package_to_pin);
    unpin(package_to_pin)?;
    println!("'{}' has been unpinned.", package_to_pin);

    Ok(())
}
```
